home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / dirscan.com / DIRSCAN.DOC < prev    next >
Encoding:
Text File  |  1989-04-01  |  7.0 KB  |  173 lines
  1.                  DIRSCAN - Scan a disk directory - V1.0
  2.  
  3. Summary
  4.  
  5.     #include dirscan.h
  6.     long  dirscan(directory,file_mask,attrib_mask,dir_exit,file_exit);
  7.  
  8.     char directory[];
  9.     char file_mask[];
  10.     char attrib_mask;
  11.     void (* dir_exit) (char[]);
  12.     void (* file_exit)(char[],struct find_t);
  13.  
  14. Description
  15.  
  16.     Searches a disk directory structure for all files matching the
  17.     file-name and extension contained in 'file_mask'.  The
  18.     arguments to dirscan are:
  19.  
  20.     char directory[]   (or char * directory)
  21.  
  22.         A null-terminated string that contains the starting path
  23.         for the directory search.  Dirscan will scan the specified
  24.         directory and all its sub-directories to their maximum
  25.         depth.
  26.  
  27.     char file_mask[]   (or char * file_mask)
  28.  
  29.         A null-terminated string that contains a standard DOS
  30.         file-name mask (i.e. possibly containing '*' and '?').
  31.         Dirscan will 'find' only files that match the specified
  32.         file mask.
  33.  
  34.     char attrib_mask
  35.  
  36.         A single byte (not a pointer) that can have bits set to
  37.         indicate that dirscan is to 'find' SYSTEM and/or HIDDEN
  38.         files in addition to normal files.  If the attrib_mask is
  39.         0x00, dirscan will 'find' only normal files.  If in
  40.         addition you want to find SYSTEM files, turn on the 0x02
  41.         bit.  To 'find' HIDDEN files, turn on the 0x04 bit.  The
  42.         Microsoft C compiler provides preprocessor variables
  43.         _A_SYSTEM and _A_HIDDEN for this purpose.  The remainder
  44.         of the bits in attrib_mask will be ignored.
  45.  
  46.     void (* dir_exit)  (char[])
  47.     void (* file_exit) (char[], struct find_t)
  48.  
  49.         Dirscan is a general-purpose utility and does not perform
  50.         any processing on the files it finds.  Instead, it calls
  51.         one of two routines that you provide to it.  The fourth
  52.         and fifth arguments to dirscan are pointers to two 'exit'
  53.         routines that dirscan calls for each directory and file
  54.         that match the specified path and file-mask.  "dir_exit"
  55.         points to a routine that dirscan will call as it begins to
  56.         scan a given subdirectory.  Normally this routine will be
  57.         used to display status information or keep track of where
  58.         dirscan is currently looking.  The pointer can be NULL, in
  59.         which case dirscan will bypass the directory exit call.
  60.  
  61.         The fifth parameter "file_exit" contains a pointer to a
  62.         subroutine that dirscan will call once for each file it
  63.         finds that matches the specified file-mask and
  64.         attrib-mask.  This routine is used to perform any required
  65.         processing.  For example, when using dirscan to implement
  66.         a "file-find" program, the file_exit routine would display
  67.         the name of the file and probably its size and timestamp.
  68.         The pointer can be NULL, in which case no file_exit
  69.         routine will be called.
  70.  
  71. Exit Routine Interface
  72.  
  73.     To use dirscan you must provide two exit routines to handle
  74.     subdirectories and files.  You can do this by defining the
  75.     routines in the module that calls dirscan.  When you call
  76.     dirscan, pass the addresses of the routines as the fourth and
  77.     fifth arguments.  Note that to pass a function pointer to a
  78.     subroutine you merely specify the name of the function to be
  79.     passed in the argument list... no leading '&' is required,
  80.     thus:
  81.  
  82.         dirscan( .....,dir_exit,file_exit);
  83.  
  84.     The exit routines must accept the following arguments:
  85.  
  86.         dir_exit (char *)
  87.  
  88.  
  89.             The dir_exit routine is called once for each new
  90.             directory examined.  It is passed a pointer to a
  91.             null-terminated string that contains the current
  92.             path-name of the sub-directory being examined.  It is
  93.             called BEFORE any files in the directory are examined.
  94.  
  95.         file_exit (char *,struct find_t)
  96.  
  97.             The file_exit routine is called once for each file
  98.             that matches the specified file_mask and attrib_mask.
  99.             The first argument to file_exit is the current
  100.             sub-directory path name.  The second is the work
  101.             buffer used by the DOS "find-first" and "find-next"
  102.             routines to return directory information.  This
  103.             structure is usually defined in <dos.h>.
  104.  
  105.     To facilitate mapping of the file date and time contained in
  106.     (struct find_t), two structure data types (typedefs) are
  107.     provide in "dirscan.h", FILE_TIME and FILE_DATE.  These
  108.     structures can be overlaid on the file time and date fields in
  109.     (struct find_t) to extract the bit fields representing the
  110.     various components of the time and date.  There is an example
  111.     of this in the file_exit routine in "locate.c".
  112.  
  113. Return Values
  114.  
  115.     The dirscan function returns the total number of files
  116.     present in the directory structure below the starting path
  117.     name.  This is NOT the number of 'found' files... it is the
  118.     number of files that would have been found had the file_mask
  119.     contained "*.*".
  120.  
  121. Usage Note
  122.  
  123.     dirscan deals with the variable depth of the directory tree
  124.     structure by calling itself recursively.  Since dirscan uses
  125.     about 160 bytes of stack space, you may run into stack
  126.     overflow when using your compiler's default stack allocation
  127.     with a highly structured directory (many levels deep).  If
  128.     this happens, increase the default stack size.
  129.  
  130. Example
  131.  
  132.     This ARC file contains a complete example of how to use
  133.     dirscan called "locate.c", which implements a "find-file"
  134.     utility routine.  The LOCATE command has the following syntax:
  135.  
  136.         LOCATE [d:][\dir\dir....\][file-name][.[ext]]
  137.  
  138.     All path components are optional and default as follows if
  139.     not specified:
  140.  
  141.         d:            The currently logged drive
  142.         \dir...       \  (root directory)
  143.         file-name     *
  144.         ext           .*
  145.  
  146.     Note that entering a filename without an extension is
  147.     equivalent to providing a ".*" extension.  To search for
  148.     occurrences of a filename with no extension you must follow
  149.     the filename with a period.  For example:
  150.  
  151.         LOCATE README    is interpreted as     LOCATE README.*
  152.  
  153.     To find files called "README" with no extension, enter
  154.  
  155.         LOCATE README.
  156.  
  157. Disclaimer
  158.  
  159.     The source code included here is placed in the public domain
  160.     and distributed AS-IS.  No .OBJ or .EXE files are included.
  161.     You must create them by compiling and linking the provided C
  162.     source code.  You are fully responsible for the results of
  163.     compiling and using these routines in your programs, and I
  164.     will assume no liability for damages, consequential or
  165.     otherwise.
  166.  
  167.     Dirscan was implemented and tested under PC-DOS 3.3 with the
  168.     Microsoft C 5.1 compiler.  Since it uses DOS interface
  169.     routines (find-first, find-next) it will probably not compile
  170.     under a different compiler without modification.
  171.  
  172.     Jim Garrison -- 76247,1747
  173.